<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Handling failure in Data Store and Concurrent Data Store applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="cam.html" title="Chapter 11.  Berkeley DB Concurrent Data Store Applications" />
    <link rel="prev" href="cam.html" title="Chapter 11.  Berkeley DB Concurrent Data Store Applications" />
    <link rel="next" href="cam_app.html" title="Architecting Data Store and Concurrent Data Store applications" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Handling failure in Data Store and Concurrent Data Store applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="cam.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 11.  Berkeley DB Concurrent Data Store
        Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="cam_fail"></a>Handling failure in Data Store and Concurrent Data Store applications</h2>
          </div>
        </div>
      </div>
      <p>
        When building Data Store and Concurrent Data Store
        applications, there are design issues to consider whenever a
        thread of control with open Berkeley DB handles fails for any
        reason (where a thread of control may be either a true thread
        or a process).
    </p>
      <p>
        The simplest case is handling system failure for any Data
        Store or Concurrent Data Store application. In the case of
        system failure, it doesn't matter if the application has
        opened a database environment or is just using standalone
        databases: if the system fails, after the application has
        modified a database and has not subsequently flushed the
        database to stable storage (by calling either the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a>,
        <a href="../api_reference/C/dbsync.html" class="olink">DB-&gt;sync()</a> or <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV-&gt;memp_sync()</a> methods), the database may be left in a
        corrupted state. In this case, before accessing the database
        again, the database should either be:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            removed and re-created,
        </li>
          <li>
            removed and restored from the last known good
            backup, or
        </li>
          <li>
            verified using the <a href="../api_reference/C/dbverify.html" class="olink">DB-&gt;verify()</a> method or <a href="../api_reference/C/db_verify.html" class="olink">db_verify</a> utility.
            If the database does not verify cleanly, the contents may
            be salvaged using the <span class="bold"><strong>-R</strong></span>
            and <span class="bold"><strong>-r</strong></span> options of the
            <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility.
        </li>
        </ul>
      </div>
      <p>
        Applications where the potential for data loss is
        unacceptable should consider the Berkeley DB Transactional
        Data Store product, which offers standard transactional
        durability guarantees, including recoverability after
        failure.
    </p>
      <p>
        Additionally, system failure requires that any persistent
        database environment (that is, any database environment not
        created using the <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag), be removed. Database
        environments may be removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> method. If
        the persistent database environment was backed by the
        filesystem (that is, the environment was not created using the
        <a href="../api_reference/C/envopen.html#envopen_DB_SYSTEM_MEM" class="olink">DB_SYSTEM_MEM</a> flag), the database environment may also be
        safely removed by deleting the environment's files with
        standard system utilities.
    </p>
      <p>
        The second case is application failure for a Data Store
        application, with or without a database environment, or
        application failure for a Concurrent Data Store application
        without a database environment: as in the case of system
        failure, if any thread of control fails, after the application
        has modified a database and has not subsequently flushed the
        database to stable storage, the database may be left in a
        corrupted state. In this case, the database should be handled
        as described previously in the system failure case.
    </p>
      <p>
        The third case is application failure for a Concurrent Data
        Store application with a database environment. There are
        resources maintained in database environments that may be left
        locked if a thread of control exits without first closing all
        open Berkeley DB handles. Concurrent Data Store applications
        with database environments have an additional option for
        handling the unexpected exit of a thread of control, the
        <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method.
    </p>
      <p>
        The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> will return 
        <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> 
        if the database environment is
        unusable as a result of the thread of control failure. (If a
        data structure mutex or a database write lock is left held by
        thread of control failure, the application should not continue
        to use the database environment, as subsequent use of the
        environment is likely to result in threads of control
        convoying behind the held locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> call will
        release any database read locks that have been left held by
        the exit of a thread of control. In this case, the application
        can continue to use the database environment.
    </p>
      <p>
        Note that by default <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> only notifies the calling thread that
        the database environment is unusable. You can optionally cause
        <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> to broadcast this to other threads of control by using
        the <code class="literal">--enable-failchk_broadcast</code> flag when you
        compile your Berkeley DB library. If this option is turned on,
        then all threads of control using the database environment will 
        return 
        <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> 
        when they attempt to obtain a mutex lock. In this situation, a
        <code class="literal">DB_EVENT_FAILCHK_PANIC</code> or <code class="literal">DB_EVENT_MUTEX_DIED</code>
        event will also be raised.  (You use <a href="../api_reference/C/envevent_notify.html" class="olink">DB_ENV-&gt;set_event_notify()</a> to examine events).
    </p>
      <p>
        A Concurrent Data Store application recovering from a thread
        of control failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>, and, if it
        returns success, the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>
        returns <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>,
        the application should proceed as
        described for the case of system failure.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="cam.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="cam.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 11.  Berkeley DB Concurrent Data Store
        Applications  </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Architecting Data Store and Concurrent Data Store applications</td>
        </tr>
      </table>
    </div>
  </body>
</html>
